From f9b6d47e5d0b4d457d16f0ae1a852172d4d3d785 Mon Sep 17 00:00:00 2001 From: Aron Xu Date: Wed, 22 Mar 2017 08:31:14 +0000 Subject: [PATCH] fix_documentation_build Gbp-Pq: Name 0005-fix_documentation_build.patch --- .../configuration/cache-basics.en.rst | 2 +- doc/admin-guide/files/records.config.en.rst | 2 +- doc/conf.py | 43 +----- .../TSHttpTxnClientPacketMarkSet.en.rst | 2 +- .../TSHttpTxnClientPacketTosSet.en.rst | 2 +- .../TSHttpTxnServerPacketMarkSet.en.rst | 2 +- .../TSHttpTxnServerPacketTosSet.en.rst | 2 +- .../api/functions/TSLifecycleHookAdd.en.rst | 2 +- .../architecture/architecture.en.rst | 6 +- .../architecture/consistency.en.rst | 2 +- doc/ext/traffic-server.py | 135 ++++++++++++++++-- 11 files changed, 143 insertions(+), 57 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index 7351d1e0..8770e8ab 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -683,7 +683,7 @@ cases the content will be buffered in ram while waiting to be sent to the client. This could potentially also happen for ``POST`` requests if the client connection is fast and the origin server connection slow. If very large objects are being used this can cause the memory usage of Traffic Server to become -`very large `_. +very large (See issue :ts:jira:`1496`). This problem can be ameliorated by controlling the amount of buffer space used by a transaction. A high water and low water mark are set in terms of bytes diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst index 4ac9e40f..cba0f200 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -1073,7 +1073,7 @@ ip-resolve performed. The result is cached (if allowed otherwise). This option is vulnerable to cache poisoning if an incorrect ``Host`` header is specified, so this option should be used with extreme caution. See - bug TS-2954 for details. + bug :ts:jira:`2954` for details. ===== ====================================================================== If all of these conditions are met, then the origin server IP address is diff --git a/doc/conf.py b/doc/conf.py index c34ad4fb..25cb5558 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -161,44 +161,9 @@ pygments_style = 'sphinx' nitpicky=1 # Autolink issue references - -from docutils import nodes -from docutils.parsers.rst import states -from docutils.utils import unescape - -# Customize parser.inliner in the only way that Sphinx supports. -# docutils.parsers.rst.Parser takes an instance of states.Inliner or a -# subclass but Sphinx initializes it from -# SphinxStandaloneReader.set_parser('restructuredtext') which is called -# from Publisher.set_components() and initializes the parser without -# arguments. - -BaseInliner = states.Inliner -class Inliner(BaseInliner): - def __init__(self): - BaseInliner.__init__(self) - - issue_pattern = re.compile(u''' - {start_string_prefix} - TS-\d+ - {end_string_suffix}'''.format( - start_string_prefix=self.start_string_prefix, - end_string_suffix=self.end_string_suffix), - re.VERBOSE | re.UNICODE) - - self.implicit_dispatch.append((issue_pattern, self.issue_reference)) - - def issue_reference(self, match, lineno): - text = match.group(0) - - rawsource = unescape(text, True) - text = unescape(text, False) - - refuri = 'https://issues.apache.org/jira/browse/' + text - - return [nodes.reference(rawsource, text, refuri=refuri)] - -states.Inliner = Inliner +# moved into traffic_server Sphinx extension +trafficserver_jira_url='https://issues.apache.org/jira/browse/' +trafficserver_github_url='https://github.com/apache/trafficserver/issues/' # -- Options for HTML output --------------------------------------------------- @@ -347,6 +312,8 @@ latex_documents = [ # documents and includes the same brief description in both the HTML # and manual page outputs. +from docutils import nodes +from docutils.utils import unescape from docutils.transforms import frontmatter from sphinx.writers import manpage diff --git a/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst index 437f528b..0272a271 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnClientPacketMarkSet.en.rst @@ -41,4 +41,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_mark_in` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_mark_in` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst index f1b694b9..d5f1f3aa 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnClientPacketTosSet.en.rst @@ -47,4 +47,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_tos_in` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_tos_in` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst index af31dd84..28c4c0df 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnServerPacketMarkSet.en.rst @@ -45,4 +45,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_mark_out` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_mark_out` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst index c412be1d..60a7f3da 100644 --- a/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst +++ b/doc/developer-guide/api/functions/TSHttpTxnServerPacketTosSet.en.rst @@ -49,4 +49,4 @@ See Also .. _Traffic Shaping: https://cwiki.apache.org/confluence/display/TS/Traffic+Shaping - :ts:cv:`proxy.config.net.sock_packet_tos_out` and TS-1090 + :ts:cv:`proxy.config.net.sock_packet_tos_out` and :ts:jira:`1090` diff --git a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst index 5499bc02..db71c926 100644 --- a/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst +++ b/doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst @@ -130,7 +130,7 @@ History ======= Lifecycle hooks were introduced to solve process initialization ordering issues -(TS-1487). Different API calls required different modules of |TS| to be +:ts:jira:`1487`. Different API calls required different modules of |TS| to be initialized for the call to work, but others did not work that late in initialization, which was problematic because all of them could effectively only be called from :func:`TSPluginInit` . The solution was to move diff --git a/doc/developer-guide/architecture/architecture.en.rst b/doc/developer-guide/architecture/architecture.en.rst index a38a1a56..07551f81 100644 --- a/doc/developer-guide/architecture/architecture.en.rst +++ b/doc/developer-guide/architecture/architecture.en.rst @@ -1147,12 +1147,12 @@ including the size of each stripe. .. [#store-disk-array] - `Work is under way `_ on - extending this to include objects that are in the memory cache. + Work is under way on extending this to include objects that are in the + memory cache (See issue :ts:jira:`2020`). .. [#coalesced-spans] This linked list is mostly ignored in later processing, causing all but one file or directory storage units on the same device to be ignored. See - `TS-1869 `_. + :ts:jira:`1869`. diff --git a/doc/developer-guide/architecture/consistency.en.rst b/doc/developer-guide/architecture/consistency.en.rst index c5d5fafd..413cff54 100644 --- a/doc/developer-guide/architecture/consistency.en.rst +++ b/doc/developer-guide/architecture/consistency.en.rst @@ -59,7 +59,7 @@ Volume Tagging ~~~~~~~~~~~~~~ Currently, :term:`cache volumes ` are allocated somewhat -arbitrarily from storage elements. `This enhancement `__ +arbitrarily from storage elements. `This enhancement :ts:jira:`1728``__ allows :file:`storage.config` to assign :term:`storage units ` to specific :term:`volumes ` although the volumes must still be listed in :file:`volume.config` in general and in particular to map domains to diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py index 50d45deb..d8de3914 100644 --- a/doc/ext/traffic-server.py +++ b/doc/ext/traffic-server.py @@ -26,7 +26,8 @@ :license: Apache """ -from docutils import nodes +from docutils import nodes, utils +from docutils.parsers.rst.roles import set_classes from docutils.parsers import rst from docutils.parsers.rst import directives from sphinx.domains import Domain, ObjType, std @@ -34,6 +35,102 @@ from sphinx.roles import XRefRole from sphinx.locale import l_, _ import sphinx +# Autolink for Trafficserver issues +# Moved from doc/conf.py, now integrated into TS domain +# +# Two types of issues supported: +# * Jira: for archive purpose only (after the Jira to Github move) +# * Github: for new issues (after the Jira to Github move) +# +# Syntax: +# :ts:jira:`XXXX` where XXXX is the issue number +# :ts:github:`XXXX` where XXXX is the issue number +# +# Output +# * Prefix issue number with 'TS-' +# * Render HTML link: +# - either to https://issues.apache.org/jira/browse/TS-XXXX +# - or to https://github.com/apache/trafficserver/issues/XXXX + +def ts_jira_role(name, rawtext, issue_num, lineno, inliner, options={}, content=[]): + """Link to a Trafficserver Jira issue. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param issue_num: The issue number marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + try: + base_url = app.config.trafficserver_jira_url + if not base_url: + raise AttributeError + except AttributeError, err: + raise ValueError('trafficserver_jira_url configuration values not set (%s)' % str(err)) + # + issue_prefix = 'TS-' + node = make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options) + return [node], [] + +def ts_github_role(name, rawtext, issue_num, lineno, inliner, options={}, content=[]): + """Link to a Trafficserver Github issue. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + try: + base_url = app.config.trafficserver_github_url + if not base_url: + raise AttributeError + except AttributeError, err: + raise ValueError('trafficserver_github_url configuration values not set (%s)' % str(err)) + # + issue_prefix = '' + node = make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options) + return [node], [] + +def make_link_node(rawtext, app, base_url, issue_prefix, issue_num, options): + """Create a link to a Apache Jira resource. + + :param rawtext: Text being replaced with link node. + :param app: Sphinx application context + :param type: Link type ('jira' or 'github') + :param slug: ID of the thing to link to + :param options: Options dictionary passed to role func. + """ + # + try: + issue_num_int = int(issue_num) + if issue_num_int <= 0: + raise ValueError + except ValueError: + raise ValueError('Trafficserver issue number must be a number greater than or equal to 1; ' + '"%s" is invalid.' % text, line=lineno) + # + base_url = base_url + issue_prefix + '{0}' + ref = base_url.format(issue_num) + set_classes(options) + node = nodes.reference(rawtext, issue_prefix + issue_num, refuri=ref, + **options) + return node + class TSConfVar(std.Target): """ Description of a traffic server configuration variable. @@ -262,6 +359,10 @@ class TSStatRef(XRefRole): def process_link(self, env, ref_node, explicit_title_p, title, target): return title, target +class TSIssueRef(XRefRole): + def process_link(self, env, ref_node, explicit_title_p, title, target): + return 'TS-' + title, 'https://issues.apache.org/jira/browse/TS-' + target + class TrafficServerDomain(Domain): """ Apache Traffic Server Documentation. @@ -273,7 +374,8 @@ class TrafficServerDomain(Domain): object_types = { 'cv': ObjType(l_('configuration variable'), 'cv'), - 'stat': ObjType(l_('statistic'), 'stat') + 'stat': ObjType(l_('statistic'), 'stat'), + 'jira': ObjType(l_('jira'), 'jira') } directives = { @@ -283,17 +385,21 @@ class TrafficServerDomain(Domain): roles = { 'cv' : TSConfVarRef(), - 'stat' : TSStatRef() + 'stat' : TSStatRef(), + 'jira' : ts_jira_role, + 'github' : ts_github_role } initial_data = { 'cv' : {}, # full name -> docname - 'stat' : {} + 'stat' : {}, + 'issue' : {} } dangling_warnings = { 'cv' : "No definition found for configuration variable '%(target)s'", - 'stat' : "No definition found for statistic '%(target)s'" + 'stat' : "No definition found for statistic '%(target)s'", + 'issue' : "No definition found for issue '%(target)s'" } def clear_doc(self, docname): @@ -305,6 +411,10 @@ class TrafficServerDomain(Domain): for var, doc in stat_list.items(): if doc == docname: del stat_list[var] + issue_list = self.data['issue'] + for var, doc in issue_list.items(): + if doc == docname: + del issue_list[var] def find_doc(self, key, obj_type): zret = None @@ -313,6 +423,8 @@ class TrafficServerDomain(Domain): obj_list = self.data['cv'] elif obj_type == 'stat' : obj_list = self.data['stat'] + elif obj_type == 'issue' : + obj_list = self.data['issue'] else: obj_list = None @@ -322,15 +434,20 @@ class TrafficServerDomain(Domain): return zret def resolve_xref(self, env, src_doc, builder, obj_type, target, node, cont_node): - dst_doc = self.find_doc(target, obj_type) - if (dst_doc): - return sphinx.util.nodes.make_refnode(builder, src_doc, dst_doc, nodes.make_id(target), cont_node, 'records.config') + if obj_type == 'issue': + return sphinx.util.nodes.make_refnode(builder, src_doc, src_doc, nodes.make_id(target), cont_node, None) + else: + dst_doc = self.find_doc(target, obj_type) + if (dst_doc): + return sphinx.util.nodes.make_refnode(builder, src_doc, dst_doc, nodes.make_id(target), cont_node, 'records.config') def get_objects(self): for var, doc in self.data['cv'].iteritems(): yield var, var, 'cv', doc, var, 1 for var, doc in self.data['stat'].iteritems(): yield var, var, 'stat', doc, var, 1 + for var, doc in self.data['issue'].iteritems(): + yield var, var, 'issue', doc, var, 1 # These types are ignored as missing references for the C++ domain. # We really need to do better with this. Editing this file for each of @@ -369,6 +486,8 @@ def setup(app): rst.roles.register_generic_role('const', nodes.literal) app.add_domain(TrafficServerDomain) + app.add_config_value('trafficserver_jira_url', None, 'env') + app.add_config_value('trafficserver_github_url', None, 'env') # Types that we want the C domain to consider built in for word in EXTERNAL_TYPES: -- 2.30.2